This file describes how to create your own custom code modules which are not part of the Preditor application itself. This allows you or third-party vendors to create added functionality to Preditor. You can perform a wide range of operations through Preditor's external interface, such as a module to stylize text based on text patterns, or perhaps a simple module that adds your electronic signature to the end of a document.
Table of Contents: (Click link to go to topic)
• General Guidelines
• Programming Interface
• Routine Reference
• Extension Flags
• Building FAT Extensions
• Demo Extensions
General Guidelines
Preditor extensions are built as a stondalone code resource of type 'CODE'. You can build such standalone code resources with CodeWarrior, Think C and MPW. There are template project files and a template source file to help get you started writing a extension. There are numerous examples as well, but all example are done using CodeWarrior. You do not need to restart Preditor when adding or removing extensions from the Extensions folder. Preditor will automatically pick up any new or updated extensions.
Each extension file contains one extension, and its resources. The 'CODE' resource of ID = 128 is the 68k code module, and the 'CODE' resource of ID = 129 is the PPC code module. All examples and the template are setup for building "FAT" code modules, so it will be easy for one to always build FAT extensions. Extensions are designed to process text, perhaps in one or more documents, and then exit. They should not put menus in the menu bar, and should not have an event loop. There are provisions to display movable modal dialogs, status dialogs, and such to help you create a interface to your extension.
If you have any relocatable blocks of memory that have pointers referencing its content, make sure you lock down that handle before you call any extension routine by calling HLock(). Any extension routine may move memory. It's also advisable to call MoveHHi() before HLock() to reduce memory fragmentation.
Extensions can display modal dialogs, alerts and call Standard File routines as long as they are removed before the extension exits. You can also call most any system services, but remember, unless you're in the middle of calling the "Display Dialog" extension routine, processing of events will not occur during the execution of the extension. You should also avoid creating your own event loop in the extension. You can, for example, send Apple Events to other applications if you do so in the middle of displaying a dialog (however, you must be careful if you send Apple Events to Preditor itself).
Programming Interface
The interface to Preditor's extension callbacks is quite simple to the person writing the extension. There are convenience macros that make calling extension interface routines as simple as making a C function call. Upon entry, your extension is passed an ExternalCallbackBlock, and a WindowRef. The callback block contains all the information necessary to make calls back into Preditor. Do not study the external callback block structure, you do not need to see it -- it should be considered private information. Always use the provided entry points to obtain any information.
To get the callback version, call extGetVersion(). For Preditor version 3, the version number is 1, and all documented entry points in this document are available to you. With new versions of Preditor, additional entry points may be added. You need to check in your extension that the callback version number before you call any entry points that were added after version 1.
The WindowRef that is passed in to your extension is the active document. All extension routines that operate on text use the active document. You can change the active document from within your extension by calling NewDocument(), OpenDocument(), or Activate().
A complete listing of all the routines that your extension can call, including prototypes, routine descriptions and how or why you would want to use a routine is available in the Routine Reference document (click link to open the routine reference).
Routine Reference
To call a routine, all you need to do in your extension source is:
ext<routine name>(callbacks, <parameters>)
For example, to insert text into the active document, you would write:
extInsert(callbacks, "Albatross", 9);
Extension Flags
All extensions should contain control flags in the form of a 4 byte resource of type 'PExt', ID = 128. The flags let Preditor know a little bit about the extension, whether it needs a document to operate on, whether it requires a document that is modifiable, whether is requires a selection, and other information.
The template extension and all example extensions included with Preditor contain a "Resource Template" that ResEdit or Resourcer will use when you edit the 'PExt' resource. If you like, you can copy the 'TMPL' resource into your resource editor, its preference file, or just leave it in the extension file.
The following is a complete list valid extension control flags. This list may grow in future versions of Preditor.
• Requires Modifiable Window
If your extension is only applicable for documents that are modifyable, set this flag. Preditor will disable the menu item in the Extensions menu that corresponds to this extension if the frontmost document is not modifyable.
• Requires Editing Window
If you want your extension to be run only when the frontmost window is a document (not the Find window, or others) , set this flag. Preditor will disable the menu item in the Extensions menu that corresponds to this extension if the frontmost window is not a document.
• Requires Selection
If your extension is only applicable for documents that have a non-empty selection (not an insertion point), set ths flag. Preditor will disable the menu item in the Extensions menu that corresponds to this extension if there is an empty selection in the frontmost document.
Building FAT Extensions
If you use the template projects provided, you can automatically build FAT extensions just by "Making" in both the 68K project file and the PPC project file. That all there is too it.
Demo Extensions
Smart Quotes
Smart Quotes will intelligently replace all ordinary quotes (" ') with smart quotes (“‘’”)
in the selected text of the frontmost document. This extension demonstrate scanning text in a document.
Rotate 13
Rotate 13 is a simple extension which transforms any alphabetical text in the selection by shift the character 13 positions over in the 26 character alphabet. Performing the rotate 13 operation twice will return the text to its original state.
Transform
Transform will add or remove a prefix/suffix string from the start or the end of all selected lines, or all lines in the frontmost document. This extension demonstrates displaying a dialog, and using the progress dialog.
Cut/Copy Matching
Cut/Copy Matching will cut or copy all lines in the selection that match a specified string. The match can be case sensitive or case insensitive. This extension demonstrates displaying a dialog, and placing accumlated text onto the clipboard.
Alphabetical Index
Alphabetical Index will create a new double-index document, and populate the major list with 26 entries named "A" through "Z". You can then use this index document as a place to store recipies, address, and the like. This extension demonstrates operating on index documents.
